Django管理文档生成器

Django的admindocs应用从模型、视图、模板标签以及模板过滤器中,为任何INSTALLED_APPS中的应用获取文档。并且让文档可以在Django admin中使用。

在某种程度上,你可以使用admindocs来快为你自己的代码生成文档。这个应用的功能十分有限,然而它主要用于文档模板、模板标签和过滤器。例如,需要参数的模型方法在文档中会有意地忽略,因为它们不能从模板中调用。这个应用仍旧有用,因为它并不需要你编写任何额外的文档(除了docstrings),并且在 Django admin中使用很方便。

概览

要启用admindocs,你需要执行以下步骤:

  • INSTALLED_APPS添加django.contrib.admindocs
  • 向你的urlpatterns添加(r'^admin/doc/', include('django.contrib.admindocs.urls'))。 确保它在r'^admin/' 这一项 之前包含,以便/admin/doc/的请求不会被后面的项目处理。
  • 安装docutils Python 模块 (http://docutils.sf.net/)。
  • 可选的: 使用admindocs的书签功能需要安装django.contrib.admindocs.middleware.XViewMiddleware

一旦完成这些步骤,你可以开始通过你的admin接口和点击在页面右上方的“Documentation”链接来浏览文档。

文档助手

下列特定的标记可以用于你的docstrings,来轻易创建到其他组件的超链接:

Django Component reStructuredText roles
Models :model:`app_label.ModelName`
Views :view:`app_label.view_name`
Template tags :tag:`tagname`
Template filters :filter:`filtername`
Templates :template:`path/to/template.html`

模型参考

admindocs页面的models部分描述了系统中每个模型,以及所有可用的字段和方法(不带任何参数)。虽然模型的属性没有任何参数,但他们没有列出。和其它模型的关联以超链接形式出现。描述由字段上的help_text属性,或者从模型方法的docstrings导出。

带有有用文档的模型看起来像是这样:

  1. class BlogEntry(models.Model):
  2. """
  3. Stores a single blog entry, related to :model:`blog.Blog` and
  4. :model:`auth.User`.
  5. """
  6. slug = models.SlugField(help_text="A short label, generally used in URLs.")
  7. author = models.ForeignKey(User)
  8. blog = models.ForeignKey(Blog)
  9. ...
  10. def publish(self):
  11. """Makes the blog entry live on the site."""
  12. ...

视图参考

你站点中的每个URL都在·页面中有一个单独的记录,点击提供的URL会向你展示相应的视图。有一些有用的东西,你可以在你的视图函数的·中记录:

  • 视图所做工作的一个简短的描述。
  • 上下文,或者是视图的模板中可用变量的列表。
  • 用于当前视图的模板的名称。

例如:

  1. from django.shortcuts import render
  2. from myapp.models import MyModel
  3. def my_view(request, slug):
  4. """
  5. Display an individual :model:`myapp.MyModel`.
  6. **Context**
  7. ``mymodel``
  8. An instance of :model:`myapp.MyModel`.
  9. **Template:**
  10. :template:`myapp/my_template.html`
  11. """
  12. context = {'mymodel': MyModel.objects.get(slug=slug)}
  13. return render(request, 'myapp/my_template.html', context)

模板标签和过滤器参考

admindocstagsfilters部分描述了Django自带的所有标签和过滤器(事实上,内建的标签参考 和 内建的过滤器参考文档直接来自于那些页面)。你创建的,或者由三方应用添加的任何标签或者过滤器,也会在这一部分中展示。

模板参考

虽然admindocs 并不包含一个地方来保存模板,但如果你在结果页面中使用:template:`path/to/template.html`语法,会使用Django的模板加载器来验证该模板的路径。这是一个非常便捷的方法,来检查是否存在特定的模板,以及展示模板在文件系统的何处存放。

包含的书签

admindocs页面上有一些很有用的书签:

Documentation for this page

Jumps you from any page to the documentation for the view that generates that page.

Show object ID

Shows the content-type and unique ID for pages that represent a single object.

Edit this object

Jumps to the admin page for pages that represent a single object.

为使用这些书签,你需要用带有is_staff 设置为 TrueUser登录Django admin,或者安装了XViewMiddleware并且你通过 INTERNAL_IPS中的IP地址访问站点。

译者:Django 文档协作翻译小组,原文:Admin documentation generator

本文以 CC BY-NC-SA 3.0 协议发布,转载请保留作者署名和文章出处。

Django 文档协作翻译小组人手紧缺,有兴趣的朋友可以加入我们,完全公益性质。交流群:467338606。